CSS Font-Size Keyword Converter - Developer Documentation

Code Organization

File Structure

The plugin is a single Python file (plugin.py) organized as follows:

Top Section (Lines 1-30):

• Imports
• Plugin metadata constants (PLUGIN_NAME, PLUGIN_VERSION)
• Configuration directory path

Helper Classes (Lines 31-70):

• ToolTip: Provides hover tooltips for UI widgets

Utility Functions (Lines 71-180):

• ensure_config_dir(): Creates config directory
• get_saved_configs(): Lists saved configuration files
• generate_unique_placeholder(): Creates UUID-based placeholders
• strip_css_comments(): Removes and saves CSS comments
• restore_css_comments(): Restores CSS comments
• is_unsafe_shorthand(): Detects complex shorthand patterns
• validate_backup_folder(): Validates backup directory

Main Entry Point (Lines 181-400):

• run(bk): Plugin entry point called by Sigil
  • Nested function build_patterns(cfg): Constructs regex patterns
  • File scanning logic
  • Calls show_file_selector()

UI Functions (Lines 401-end):

• show_config_window(): Configuration dialog
• show_unsafe_css_dialog(): Unsafe pattern warning
• show_shorthand_preview_dialog(): Safe shorthand preview
• show_preview_window(): All changes preview
• show_file_selector(): Main file selection window

Function Dependencies

Key Data Flow

1. Configuration → Stored in Sigil preferences + JSON files
2. Scanning → Files with keywords → File list with metadata
3. User Selection → Checked files → Selected file list
4. Categorization → Changes → safe_changes, shorthand_changes, unsafe_items
5. Conversion → Modified text → Write to book
6. Undo → Memory backup → Restore original content

Common Modification Tasks

Adding a New Keyword

Step 1: Add to keywords list in build_patterns() (around line 220):

keywords = [
    # ... existing keywords
    ('new-keyword', 'newkeyword', 'newkeyword_unit'),
]

Step 2: Add default values in run() function (around line 195):

config = {
    # ... existing configs
    'newkeyword': prefs.get('newkeyword', '1.5'),
    'newkeyword_unit': prefs.get('newkeyword_unit', 'em'),
}

Step 3: Add to UI in show_config_window() (around line 550):

keywords = [
    # ... existing keywords
    ('new-keyword', 'newkeyword'),
]

Step 4: Add to defaults in reset_defaults() (around line 730):

defaults = {
    # ... existing defaults
    'newkeyword': '1.5',
}

Adding a New Unit Type

To add support for ch, vw, or other CSS units:

Step 1: Modify radio button creation in show_config_window() (around line 580):

# Add new radio button column
ch_header = Label(config_frame, text="ch", font=('Arial', 10, 'bold'), width=5)
ch_header.grid(row=0, column=4, pady=5)

# In the loop for each keyword:
Radiobutton(config_frame, text="", variable=unit_var,
           value='ch').grid(row=idx, column=4, pady=3)

Step 2: Update bulk set buttons:

def set_all_ch():
    for unit_var in unit_vars.values():
        unit_var.set('ch')

all_ch_btn = Button(bulk_frame, text="All ch", command=set_all_ch, width=10)
all_ch_btn.pack(side=LEFT, padx=5)

Adding New Validation Rules

To add validation to is_unsafe_shorthand() (around line 155):

def is_unsafe_shorthand(css_line):
    # ... existing checks
    
    # New rule: reject if contains attr() function
    if re.search(r'\battr\s*\(', font_value, re.IGNORECASE):
        return True
    
    return False

Modifying UI Layout

Changing window size: Look for .geometry() calls:

# In show_config_window():
window_width = min(750, int(screen_width * 0.8))  # Adjust multiplier

Changing colors: Search for color codes:

# Find and replace hex codes like:
background='#ffd6d6'  # Pink
background='#cce5ff'  # Blue
foreground='#FF0000'  # Red

Adding new checkbox to config: Add after existing checkboxes (around line 615):

new_feature_var = BooleanVar(value=config.get('new_feature', 'false') == 'true')
new_check = Checkbutton(frame, text="Enable new feature", variable=new_feature_var)
new_check.pack(anchor=W, pady=(0, 5))

Adding File Filters

To add a filter for SVG files in the file selector (around line 1180):

Step 1: Add checkbox variable:

show_svg = BooleanVar(value=False)

Step 2: Add checkbox to filter_frame:

cb_svg = Checkbutton(filter_frame, text="Show SVG Files", variable=show_svg,
    command=lambda: [show_all.set(False), show_text.set(False), 
                     show_css.set(False), update_filter()])
cb_svg.pack(side=LEFT, padx=5)

Step 3: Modify populate_checkboxes():

if show_svg.get():
    filtered_files = [f for f in files_with_keywords if f['type'] == 'svg']

Debugging Guide

Testing Without Sigil

Create a mock book container object:

class MockBook:
    def __init__(self):
        self.prefs = {}
        self.files = {
            'css1': 'body { font-size: small; }',
            'html1': '<p style="font-size: large;">Test</p>'
        }
    
    def getPrefs(self):
        return self.prefs
    
    def savePrefs(self, prefs):
        self.prefs = prefs
    
    def css_iter(self):
        return [('css1', 'style.css')]
    
    def text_iter(self):
        return [('html1', 'page.html')]
    
    def readfile(self, file_id):
        return self.files.get(file_id, '')
    
    def writefile(self, file_id, content):
        self.files[file_id] = content

# Test:
bk = MockBook()
run(bk)

Common Failure Points

1. Regex Pattern Errors

• Symptom: No matches found when they should exist
• Diagnosis: Print the compiled pattern and test string
• Fix: Check keyword escaping, ensure proper lookahead syntax

# Debug pattern matching:
pattern = compiled_patterns[0][0]  # First pattern
test_line = "font-size: small;"
print(f"Pattern: {pattern.pattern}")
print(f"Match: {pattern.search(test_line)}")

2. Comment Placeholder Collision

• Symptom: CSS corrupted after conversion
• Diagnosis: Check if placeholder appears in original CSS
• Fix: Verify UUID generation is working

# Test placeholder uniqueness:
css = "/* test */ body { font-size: small; }"
text, pmap = strip_css_comments(css)
print(f"Placeholders: {list(pmap.keys())}")
restored = restore_css_comments(text, pmap)
assert restored == css

3. Checkbox State Issues

• Symptom: Checkboxes stay disabled after undo
• Diagnosis: Check if all checkboxes are being re-enabled
• Fix: Ensure loop iterates all children

# Debug checkbox state:
for widget in checkbox_frame.winfo_children():
    print(f"{widget} state: {widget['state']}")

4. Backup Validation Failures

• Symptom: Backup fails silently
• Diagnosis: Check folder permissions and path
• Fix: Add verbose error logging

# Test backup validation:
is_valid, error = validate_backup_folder('/path/to/folder')
print(f"Valid: {is_valid}, Error: {error}")

Verbose Logging

Add debug prints throughout:

def strip_css_comments(css_text):
    print(f"DEBUG: Input length: {len(css_text)}")
    # ... processing
    print(f"DEBUG: Found {len(placeholder_map)} comments")
    return text_no_comments, placeholder_map

To disable in production, use a global flag:

DEBUG = False  # Set at top of file

def debug_print(msg):
    if DEBUG:
        print(msg)
        sys.stdout.flush()

Testing Regex in Isolation

import re

keyword = 'small'
escaped = re.escape(keyword)
pattern = rf'(font-size\s*:\s*){escaped}(\s*(?=[;}}"\'\!]|$))'
regex = re.compile(pattern, re.IGNORECASE | re.MULTILINE)

test_cases = [
    'font-size: small;',
    'font-size:small;',
    'font-size: SMALL;',
    'font-size: small !important;',
    'font-size: smaller;',  # Should not match
]

for test in test_cases:
    match = regex.search(test)
    print(f"{test:30} -> {bool(match)}")

Platform-Specific Issues

Windows:

• Path separators: Use os.path.join() always
• Test with paths containing spaces
• Check for Windows-specific file locking

macOS:

• Tkinter rendering differences
• Test on Retina displays (DPI scaling)
• File permissions may differ

Linux:

• Different desktop environments (GTK vs Qt)
• Font rendering variations
• Check .sigil folder creation permissions

Known Issues & Limitations

Edge Cases Not Handled

1. Font Shorthand with System Keywords

font: small caption;  /* 'caption' is system font, not family */

Plugin will convert 'small' but result may be incorrect.

2. Multiple Font-Size in Same Declaration

font-size: large; font-size: small;  /* Last one wins */

Plugin converts both, even though only last matters.

3. Keywords in Attribute Selectors

[title~="small"] { font-size: 12px; }

Pattern won't match (correct behavior), but worth noting.

4. CSS Variables Containing Keywords

--my-size: small;  /* Variable assignment */
font-size: var(--my-size);  /* Usage */

Plugin won't convert variable assignment or usage (correct for safety).

5. Very Long Lines

If a CSS line exceeds ~10,000 characters, regex performance may degrade significantly.

Performance Characteristics

Scaling:

• 1-10 files: Instant (<1 second)
• 100 files: 2-5 seconds
• 1000+ files: May take 30+ seconds

Memory usage:

• Stores all file contents in memory for undo
• Large books (100+ MB) may cause slowdowns
• Consider adding progress bar for 100+ files

Regex Performance:

• Comment stripping: O(n) where n = file size
• Pattern matching: O(n*m) where m = number of patterns
• Optimization opportunity: Compile patterns once globally

Tkinter Quirks

Canvas Scrolling:

• Must call update_idletasks() before setting scroll region
• Scrollbar may not appear until window is resized on some platforms

Dialog Modality:

• transient() + grab_set() required for proper modal dialogs
• On macOS, may need to call lift() to bring to front

Text Widget Performance:

• Inserting >10,000 lines becomes slow
• Consider pagination for very large preview

Sigil Version Compatibility

Tested with:

• Sigil 1.9.x - 2.x

API assumptions:

• bk.css_iter() returns (file_id, href) tuples
• bk.text_iter() returns (file_id, href) tuples
• bk.readfile() accepts file_id, returns bytes or string
• bk.writefile() accepts file_id and string
• bk.getPrefs() / bk.savePrefs() for persistence

Design Decisions & Rationale

Why UUID Placeholders Instead of Sequential Numbers?

Decision: Use uuid.uuid4().hex for comment placeholders

Rationale:

• Sequential numbers (___COMMENT_0___, etc.) could exist in original CSS
• Even checking for conflicts would require scanning entire file
• UUIDs are effectively guaranteed unique (collision probability ~10^-36)
• Slight performance cost is negligible compared to file I/O

Rejected alternatives:

• Base64 encoding comments: Hard to debug, similar collision risk
• Hash-based placeholders: Still possible collisions with short hashes

Why Memory Backup + Optional External Backup?

Decision: Always store originals in memory, optionally write to disk

Rationale:

• Memory backup enables instant undo within same session
• External backup provides safety if Sigil crashes
• Users can choose based on their needs and disk space
• Combined approach balances convenience and safety

Rejected alternatives:

• External backup only: Slow, requires disk I/O, folder management
• Memory only: No recovery if plugin or Sigil crashes
• Sigil's built-in checkpoints: User must remember to create them manually

Why Two Dialogs for Unsafe/Safe Shorthand?

Decision: Separate "Unsafe CSS Detected" and "Review Safe Shorthand Changes"

Rationale:

• Different user actions required (acknowledge vs choose)
• Separates "warning" from "decision"
• Users see unsafe items before committing to preview safe items
• Clearer mental model: filter out bad, then decide on good

Rejected alternatives:

• Single combined dialog: Too much information, confusing actions
• No preview: Users can't review what will change
• Skip unsafe silently: Users might not notice skipped items

Why Checkboxes Instead of Listbox?

Decision: Individual checkboxes for each file

Rationale:

• More intuitive for users (no Ctrl+Click required)
• Clear visual state (checked = selected)
• Accessible: Works with keyboard navigation
• Standard UI pattern for multi-select

Rejected alternatives:

• Listbox with EXTENDED mode: Requires platform-specific key combos
• Radio buttons: Only single selection
• Tree view: Overkill for flat file list

Tradeoffs Made

Simplicity vs Features:

• No support for CSS preprocessor variables (Sass, Less)
• No batch processing multiple books
• No custom keyword definitions
• Why: 80/20 rule - covers most use cases, avoids complexity

Performance vs Safety:

• Line-by-line processing instead of whole-file regex
• Why: Easier to track line numbers, safer for large files

Flexibility vs Usability:

• Fixed keyword set, not user-extensible
• Why: Prevents invalid CSS, simpler UI

Testing Strategy

Manual Test Cases

Create two test files (provided separately):

• test-styles.css: External CSS
• test-page.html: HTML with embedded styles and inline attributes

Pre-Conversion Checks:

1. Plugin loads without errors
2. Finds both test files
3. Counts matches accurately
4. Configuration loads with defaults

Conversion Tests:

Basic (Shorthand Disabled):

1. Select both files, click Preview
2. Verify only font-size: changes shown
3. Apply changes
4. Verify conversions in files
5. Click Undo
6. Verify files restored to original

Shorthand (Enabled):

1. Open Configuration, enable shorthand
2. Select both files, click Apply
3. Should see "Unsafe CSS Detected" dialog
4. Click Continue
5. Should see "Review Safe Shorthand Changes" dialog
6. Click "Apply All"
7. Verify both font-size: and safe font: converted
8. Verify unsafe items skipped

Edge Cases:

1. Cancel at each dialog, verify no changes made
2. Filter by HTML only, verify CSS file hidden
3. Change units to rem, verify rem used in output
4. Create external backup, verify files created with timestamp
5. Modify numeric values, verify custom values used

Error Handling:

1. Select invalid backup folder, verify error shown
2. Enter negative number in config, verify validation error
3. Enter non-numeric value, verify validation error

Regression Testing

After any code change, verify:

1. All keyword conversions still work
2. Comments preserved correctly
3. Shorthand safety detection works
4. Backup/undo cycle works
5. Configuration save/load works
6. No crashes in any workflow

User Acceptance Criteria

Plugin is ready for release when:

• All test cases pass
• No errors in Sigil debug log
• Undo restores exact original content
• External backups created when enabled
• Preview matches actual changes
• Configuration persists across sessions
• Works on Windows, macOS, Linux
• UI is responsive (no freezing)
• All tooltips display correctly

Release Process

Version Numbering

Format: MAJOR.MINOR.PATCH

Increment:

• MAJOR: Breaking changes (incompatible with previous versions)
• MINOR: New features (backward compatible)
• PATCH: Bug fixes only

Current: 0.7.0

• 0.x.x = Pre-release, may have breaking changes
• 1.0.0 = First stable release

Pre-Release Checklist

• All tests pass
• Version number updated in code (PLUGIN_VERSION)
• User documentation updated
• Developer documentation updated
• Test files included
• README.md updated
• CHANGELOG.md updated

Packaging for Sigil

File structure:

plugin.xml example:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
  <name>CSS Font-Size Keyword Converter</name>
  <type>edit</type>
  <author>Your Name</author>
  <description>Converts CSS font-size keywords to em/rem units</description>
  <version>0.7.0</version>
  <engine>python3.4</engine>
</plugin>

Creating plugin ZIP:

1. Place files in NewUnit/ folder
2. Create ZIP: NewUnit_v0.7.0.zip
3. Test installation in clean Sigil instance

Distribution

Official Sigil Plugin Repository:
Submit to: https://www.mobileread.com/forums/forumdisplay.php?f=237

GitHub Release:

1. Create tag: v0.7.0
2. Upload ZIP file
3. Write release notes

Release Notes Template:

## Version 0.7.0 - YYYY-MM-DD

### New Features
- Feature description

### Bug Fixes
- Fix description

### Known Issues
- Issue description

### Upgrade Notes
- Migration instructions if needed

Changelog Management

Keep CHANGELOG.md updated with:

• Date of each release
• List of changes in categories: Added, Changed, Fixed, Removed
• Link to GitHub issues/PRs if applicable

Code Conventions

Naming Patterns

Functions:

• lowercase_with_underscores()
• Verbs for actions: validate_folder(), show_dialog()
• is_*() for boolean predicates

Variables:

• lowercase_with_underscores
• Descriptive names: file_checkboxes not fc
• UI components: *_frame, *_btn, *_label, *_var

Constants:

• UPPERCASE_WITH_UNDERSCORES
• Module-level only: PLUGIN_NAME, PLUGIN_VERSION, CONFIG_DIR

Exceptions:

• Single-letter loop variables acceptable: i, idx, e (for exceptions)
• Tkinter convention: capital letters for widget classes (Frame, Button, etc.)

Global vs Local Scope

Use Global Scope For:

• Plugin metadata constants
• Utility functions (don't depend on book object)
• Class definitions

Use Local Scope For:

• Nested functions that need closure over local variables
• UI callbacks that reference UI elements
• Temporary processing functions

Avoid:

• Global mutable state
• Module-level variables that change

Error Handling Patterns

File Operations:

try:
    # operation
except (IOError, OSError) as e:
    print(f'Error: {e}')
    sys.stdout.flush()
    # continue or return

User Input Validation:

try:
    value = float(input_str)
    if value <= 0:
        show_error("Must be positive")
        return False
except ValueError:
    show_error("Must be a number")
    return False

Always:

• Log errors to stdout with sys.stdout.flush()
• Show user-friendly error dialogs for UI issues
• Continue processing other files if one fails
• Never let exceptions crash the plugin

Comment Style

Module/Function Docstrings:

def function_name(param):
    """
    Brief description of what function does
    
    Args:
        param: Description
    
    Returns:
        Description of return value
    """

Inline Comments:

• Explain WHY, not WHAT (code shows what)
• Use for non-obvious design decisions
• Mark TODOs with # TODO: description

Section Headers:

# ===== SECTION NAME =====
# For major sections of code

Dependencies & Compatibility

Python Version Requirements

Minimum: Python 3.4 (matches Sigil's requirement)
Recommended: Python 3.8+
Tested: Python 3.9, 3.10, 3.11

To support Python 3.4-3.5:
Replace f-strings with .format():

# Instead of:
f"Error: {msg}"

# Use:
"Error: {}".format(msg)

Standard Library Dependencies

All imports are from standard library:

• re: Regex pattern matching
• sys: stdout flushing, exit codes
• os: Path operations, directory creation
• json: Configuration file format
• uuid: Unique placeholder generation
• datetime: Timestamp generation for backups
• tkinter: GUI framework

Tkinter Version Differences

Python 3.x uses tkinter (lowercase)

from tkinter import *
from tkinter import ttk, filedialog, messagebox

Not compatible with Python 2.x (which used Tkinter)

Tkinter features used:

• Basic widgets: Frame, Label, Button, Entry, Checkbutton, Radiobutton
• Scrollable widgets: Canvas, Scrollbar, Listbox, Text
• Dialogs: Toplevel, messagebox, filedialog
• Variables: StringVar, BooleanVar

Sigil API Requirements

Book Container Methods Used:

Assumptions:

• readfile() may return bytes or string (plugin handles both)
• File IDs are unique and stable within session
• Preferences persist across Sigil sessions

Version Notes:

• Sigil 0.9.x - 1.x: API stable
• Sigil 2.x: API unchanged from 1.x
• Future versions: May require testing

Cross-Platform Considerations

File Paths:

• Always use os.path.join(), never hardcode / or \
• Handle spaces in paths (use quotes if needed)
• Case sensitivity: macOS/Linux are case-sensitive, Windows is not

Tkinter Rendering:

• Font rendering differs by platform
• Window positioning may need adjustment
• DPI scaling (HiDPI/Retina) handled automatically by Tkinter

Configuration Storage:

• ~/.sigil/ on macOS/Linux
• %APPDATA%/sigil/ on Windows
• os.path.expanduser('~') handles both

Line Endings:

• CSS/HTML files may have CRLF (Windows) or LF (Unix)
• Plugin preserves whatever line endings are in original
• Python handles transparently in text mode

Permissions:

• Backup folder must be writable
• Configuration directory creation may fail on restricted systems
• Plugin gracefully handles permission errors

Appendix: Quick Reference

Common File Locations

Plugin file: plugin.py
Config storage: ~/.sigil/NewUnit/configs/*.json
Temp backup test: <backup_folder>/.write_test_<uuid>.tmp

Key Functions Quick Reference

Configuration Keys

UI Color Codes

Exit Codes

Document Version: 1.0
Last Updated: 2025-01-15
Contact: [maintainer email/github]